FreeSpins

Activation and Cancellation of FreeSpins

The Evenbet system utilizes two main URLs for managing FreeSpins during interaction with the provider: one for activating FreeSpins and one for their cancellation.

Activation of FreeSpins Package

Before starting the game, the system checks if the user has active FreeSpins. In case FreeSpins are available, a request is sent to the provider to create and activate the FreeSpins in their system at the URL FREESPINS_OPERATIONS_URL/activate. The request is considered successful if the HTTP status code is 200 or 201.

To initiate the creation and activation of a FreeSpins package on the provider's end, a POST request is sent to the provider's system to the URL FREESPINS_OPERATIONS_URL/activate. A POST request includes the following mandatory parameters in JSON format and an Authorization token in the headers:

Request

Header	Description	Mandatory	Type
Authorization	Authorization token	+	string

Parameter	Description	Mandatory	Type
id	EvenBet FreeSpin package ID	+	integer
userId	The ID of the user in the Evenbet system	+	integer
gameList	Provider's game IDs array	+	array
currency	FreeSpins currency ISO code	+	string
quantity	Number of FreeSpins available	+	integer
expirationDate	FreeSpin package expiration date in timestamp format	+	integer
casinoId	Casino operator ID (is sent at the provider's request)	-	string

The provider returns a response with the mandatory parameter freespinsId and an optional parameter message. In case of an unsuccessful result, the FreeSpins are not activated, and the game starts.

Headers Example:

    "Authorization ": "hash_of_request_and_secret_key"

Request example:

{
    "id": 9,
    "userId": 40,
    "gameList": ["test_game_id"],
    "currency": "EUR",
    "quantity": 10,
    "expirationDate": 1725449260,
    "casinoId": "test_casino_id"
}

Response

Parameter	Description	Mandatory	Type
freespinsId	FreeSpins ID on the provider's side	+/-	string (Mandatory in case of a success response)
message	Error message	+/-	string (Mandatory in case of an error response)

Example of a success response:

{
    "freespinsId": "provider_freespin_id"
}

Example of an error response:

{
 "error": { 
   "code": 410, 
    "message": "Error Code 10, Invalid used FreeSpin package ID" 
  } 
}

In case of a successful response, the FreeSpins are activated on Evenbet's side. In case of an unsuccessful response, the FreeSpins are not activated on Evenbet's side.

Cancellation of FreeSpins Package

If the FreeSpins package has expired or has been cancelled in the Evenbet system, a cancellation request is sent to the URL FREESPINS_OPERATIONS_URL/cancel. The request is considered successful if the HTTP status code is 200.

Request

Header	Description	Mandatory	Type
Authorization	Authorization token	+	string

Parameter	Description	Mandatory	Type
id	EvenBet FreeSpin package ID	+	integer
casinoId	Casino operator ID (is sent at the provider's request)	-	string

Headers Example:

    "Authorization": "hash_of_request_and_secret_key"

Request example:

{
    "id": 9,
    "casinoId": "test_casino_id"
}

Response

Parameter	Description	Mandatory	Type
freespinsId	FreeSpins ID on the provider's side	+/-	string (Mandatory in case of a success response)
message	Error message	+/-	string (Mandatory in case of an error response)

Example of a success response:

{
    "freespinsId": "provider_freespin_id"
}

Example of an error response:

{
 "error": { 
   "code": 7, 
    "message": "Error Code 7, Invalid token" 
  } 
}

Authorization

Requests for the activation and cancellation of FreeSpins include an Authorization token in the headers. The algorithm for generating this token is the same as the one used for callbacks. The provider must validate the Authorization token, process the FreeSpins request, and return a positive response only if the Authorization is valid.

Idempotency

Our requests are idempotent. This means that if a repeated request for activation or cancellation of FreeSpins is sent, the provider should give the same response as the first time. For example, if a FreeSpin has already been added on the provider's side but we send the request again with the same ID and casinoId, the provider should return a successful response with the already added freespinsId. A provider MUST NOT activate new FreeSpins if FreeSpins with the same FreeSpinsId and casinoId have already been activated on the provider's side. The same should apply to the cancel request.

---

Callbacks

Debit

The debit callback facilitates the deduction of funds from a user's balance within the casino platform.

Note: All rounds must have at least one debit transaction.

{server-name}/api/web/casino/providers/{provider-name}/debit

Request

Parameter	Description	Mandatory	Type
token		+	string
gameId	Game ID	+	string
endRound	Shows if the round is completed	+	bool
roundId	Game round ID	+	string
transactionId	External transaction ID	+	string
amount	Bet amount (For FreeSpins bet amount can be zero)	+	float
freeSpinPackageId	used Evenbet FreeSpins' package ID	+	integer
usedFreeSpinsQuantity	The number of used FreeSpins. In case this parameter is not passed, default values are used.	+/-	integer

Example of the request body:

{
    "token" : "46e42cb6773df9e8530e341a4fd0596d",
    "gameId" : "some-game",
    "endRound" : false,
    "roundId" : "test-round-1",
    "transactionId" : "test-transaction-0912",
    "amount" : 100,
}

Response

Parameter	Description	Mandatory	Type
balance	Current user’s balance	+	float
transactionId	Internal transaction ID	+	string
timestamp	The time when request was processed	+	string

Example of the response body:

{
    "balance": 9900,
    "transactionId": "86",
    "timestamp": "1659925530134",
}

Credit

The credit callback is used to credit winnings to a user's account within the casino platform.

{server-name}/api/web/casino/providers/{provider-name}/credit

Note: Credit transaction can only be created if there is a completed debit transaction in the round or if there is a rolled back debit transaction in the round in case the amount of the current transaction is 0.

Request

Parameter	Description	Mandatory	Type
token		+	string
gameId	Game ID	+	string
endRound	Shows if the round is completed	+	bool
roundId	Game round ID	+	string
transactionId	External transaction ID	+	string
amount	FreeSpins winnings amount	+	float
freeSpinPackageId	Used Evenbet FreeSpins' package ID	+	integer
usedFreeSpinsQuantity	The number of used FreeSpins. In case this parameter is not passed, default values are used.	+/-	integer

Example of the request body:

{
    "token" : "46e42cb6773df9e8530e341a4fd0596d",
    "gameId" : "some-game",
    "endRound" : true,
    "roundId" : "test-round-1",
    "transactionId" : "test-transaction-0912",
    "amount" : 200,
}

Response

Parameter	Description	Mandatory	Type
balance	Current user’s balance	+	float
transactionId	Internal transaction ID	+	string
timestamp	The time when request was processed	+	string

Example of the response body:

{
    "balance": 1100,
    "transactionId": "87",
    "timestamp": "1659925530134",
}

UsedFreeSpinsQuantity Parameter Additional Details

Below, you can find the accepted Debit-Credit transaction patterns in relation to the usedFreeSpinsQuantity parameter.

Example: freeSpinPackageId = 100 was issued to a player, with count = 3.

• Alternating Debit and Credit Transaction requests:

  • debit transaction: usedFreeSpinsQuantity = 1
  • credit transaction: usedFreeSpinsQuantity = 0
  • debit transaction: usedFreeSpinsQuantity = 1
  • credit transaction: usedFreeSpinsQuantity = 0
  • debit transaction: usedFreeSpinsQuantity = 1
  • credit transaction: usedFreeSpinsQuantity = 0

• Multiple or Single Debit Transaction requests Followed by a Single Credit Transaction request

  • debit transaction: usedFreeSpinsQuantity = 1
  • debit transaction: usedFreeSpinsQuantity = 1
  • debit transaction: usedFreeSpinsQuantity = 1
  • credit transaction: usedFreeSpinsQuantity = 0

• One or Multiple Credit Transaction requests

  • credit transaction: usedFreeSpinsQuantity = 3

tip

If the usedFreeSpinsQuantity parameter cannot be passed by the provider, it can be omitted. In this case, Evenbet will automatically populate this information using default values based on the transaction type:

• For debit transactions: usedFreeSpinsQuantity = 1.
• For credit transactions: usedFreeSpinsQuantity = 0.